Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / edfile.dqc / EDFILE.DOC

Wrap

Text File | 1985-09-13 | 19.3 KB | 422 lines

EDFILE UTILITY USAGE Jan 10, 1984 by Mike Mosko, K3RL EDFILE is a public domain utility which allows display and editing of data in files. It has been tested and run under CP/M- 80 version 2.2 and TurboDOS 1.2 and should run in any CP/M-80 type environment. EDFILE is approximately 11k in size. EDFILE may be freely distributed to whomever desires it. The date of this document should agree with the version date in EDFILE. FEATURES: ======== - Hex and ASCII display of record data. - Screen editing of selected record. - Hex or ASCII input when editing file records. - Fully programmable cursor control. - Powerful file search capabilities. - Forward and backward record scrolling. - Address and/or record number referencing. - Decimal or Hex number inputs. - Disk reset on input (prevents Disk R/O error). - Full online abbreviated help AND expanded help menus. INSTALLATION: ============ The following information will aid the user when installing EDFILE on a different terminal. The EDFILE original distribution program is originally configured for an ADM-3A type terminal or equivalent (I use a Digilog S1500). The terminal must be able to display 80 columns by 24 rows. The only absolutely necessary function required for proper use is the cursor positioning function. Other functions that can be added merely for visual purposes are the cursor on, cursor off and clear to end-of-line functions. If the clear to end-of-line function is not preprogrammed, it is performed in software. These functions are not implemented in the original distribution version of EDFILE. For ADM-3A type terminals, the following commands can be patched in EDFILE if these attributes are desired: Clear to end-of-line .... ESC 'Q' (1B,51) Enable Cursor ........... ESC 'X' (1B,58) Disable Cursor .......... ESC 'Y' (1B,59) For example, to add the clear to end-of-line function, patch a 02 for the string length (2 bytes for the sequence) at address 146. Then patch a 1B in location 147 and a 51 in location 148. Certain functions are programmable for the type of terminal in use. Five bytes are reserved for each terminal function (string sequence). The first byte represents the length of the string sequence. For example: the initial cursor positioning string for an ADM-3A terminal is 'ESC ='. This is two bytes in length. Therefore, the values inserted into the cursor positioning sequence area are (in hex): 02,1B,3D. To complete the cursor positioning sequence for the terminal, the row and column must be issued as well. The ADM-3A requires an adjustment value (or offset) of 32 decimal (20 hex) be added to the row and column. For terminals that require a different offset, this value can be changed as well. The row is usually sent before the column, but if your terminal is different, i.e., the column must be issued first, then set the high order bit of the cursor offset value. This flags the cursor positioning routine to send the column before the row. The following addresses detail the location of the modifiable parameters for the terminal. Address Default (hex) Function ------- ------------- -------- 140 02,1B,3D,00,00 *Initial cursor positioning string sequence 145 20 *Row/column adjustment (set high bit for column/row) 146 00,00,00,00,00 Clear to end-of-line string sequence 14B 00,00,00,00,00 Enable cursor (cursor on) string sequence 150 00,00,00,00,00 Disable cursor (cursor off) string sequence 155 08 Cursor left (normally CTRL-H) 156 0C Cursor right (normally CTRL-L) 157 0B Cursor up (normally CTRL-K) 158 0A Cursor down (normally CTRL-J) 159 00..........00 Terminal initialization string (35 bytes) * - Must be implemented. If your terminal requires some sort of initialization string, either to preset it or to program a function key pad, this can be inserted into the terminal initialization string area provided. The first byte represents the length of the string to be issued to the terminal. There are 35 bytes available for an initialization string. Why so many? The Digilog S1500 computer I use allows reprogramming of the numeric keypad. This requires 28 bytes. The actual control sequences for positioning the cursor (up, down, left and right) can be changed. This is provided for terminals that have cursor positioning keypads which don't issue the same ones programmed here. For example: usually a CTRL-L moves the cursor one space to the right. However, if your cursor pad issues some other control character, like a CTRL-D (WordStar type), then patch a 04 (hex equivalent of CTRL-D) for the cursor right value. Note, the help menus will still display the default values for up, down, left and right cursor movements. You'll have to make a note about this or, better yet, use EDFILE to patch the help menus. All of the above modifications (patches) can be made easily with EDFILE itself. Of course, if it won't run at all, you'll have to resort to some sort of debugger such as DDT, SID, MONITOR, etc..., or better yet, use someone elses computer with a (working) version of EDFILE to modify it for your terminal. EDFILE should work on virtually all terminals currently in use. There may be some real strange ones out there that I don't know about, but that's life. OPERATION: ========= EDFILE is simple to use especially with the online help menus. Therefore, just a few tidbits of information is provided here for operation. To invoke EDFILE, simply type EDFILE followed by the name of the file you wish to dump and/or edit. Example: EDFILE EDFILE.COM The display should look similar to the following: ----------------------------------------------------------------- Vers: 01-10-84; by: J.C.Kaltwasser & M.J.Mosko, K3RL File: EDFILE.COM Record: 00000 (0000H) LOF: 00086 (0056H) 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 0123456789ABCDEF -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- ---------------- 0100 - 31 EA 01 C3 EA 01 0D 0A 56 65 72 73 3A 20 30 31 >1j.Cj...Vers: 01< 0110 - 2D 31 30 2D 38 34 3B 20 62 79 3A 20 4A 2E 43 2E >-10-84; by: J.C.< 0120 - 4B 61 6C 74 77 61 73 73 65 72 20 26 20 4D 2E 4A >Kaltwasser & M.J< 0130 - 2E 4D 6F 73 6B 6F 2C 20 4B 33 52 4C 0D 0A 24 1A >.Mosko, K3RL..$.< 0140 - 02 1B 3D 00 00 20 00 00 00 00 00 00 00 00 00 00 >..=.............< 0150 - 00 00 00 00 00 08 0C 0B 0A 00 00 00 00 00 00 00 >................< 0160 - 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 >................< 0170 - 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 >................< ----------------------------------------------------------------- EDFILE performs an automatic disk reset (^C) when executed. Therefore, don't panic if you suddenly realized you forgot to perform a Control-C after making some changes. This prevents the infamous (and frustrating) Bdos Err on A: R/O from occuring when writing records. The LOF means the Length-Of-File which is the total number of records in the file. Record numbers begin at 0; the last displayable record number is actually the LOF - 1. If you don't specify a file on the command line, you'll get an error: "No File Specified."; or if the file is not found, you'll get an error telling you this: "<filename> Not Found." Simple. At the ? prompt, type 'H'. The brief help menu will be displayed: ----------------------------------------------------------------- Read/Edit File Utility Functions: A - Address to dump B - Dump at beginning C - Continue Search E - Enter Edit Mode H - This help list M - Expanded Help list O - Set address offset Q - Quit this program R - Read & dump record S - Search for string Z - Dump at end of file CR - (+/=) - Adv record (-/_) - Decr record Edit Mode Functions: ^E - Toggle data fields ^W - Write buffer out ^X - Abort Edit Mode ^J - Cursor Down ^K - Cursor Up ^H - Cursor Left ^L - Cursor Right ----------------------------------------------------------------- Again at the ? prompt, type 'M'. This will display the expanded help menu. ----------------------------------------------------------------- Read/Edit File Utility Functions: A - Enter relative address to dump B - Set record to beginning of file and dump data C - Continue search. Restarts search on last entered search string. E - Enter Edit mode on current record H - Brief description of the functions M - This help description O - Enter offset address relative to start of file (.COM = 100h) Q - Quit program R - Enter record number to dump S - Search for hex or ASCII string in file (starts at current record) '\' = ASCII string delimiters (ex: \Test\) ',' = hex and/or ASCII delimiters (ex: 41,\Test\,4A ';' = select search options A - Start search from beginning of file B - Search Backwards M - Search on certain bits set; use mask xx O - Stop on xx occurrence of string U - Translate lower case characters to upper case Z - Search recognition on least significant 7 bits only Z - Set record to end of file and dump data CR - carriage return (or +/= key) - advances record and dumps the data -/_ key - decrements record and dumps the data Edit mode: ('^' refers to the Control key) ^[ - (ESC) Accept next char into edit field even if a control char ^E - Toggle between ASCII and hex data fields ^W - Flush record to disk ^X - Abort edit mode without updating record ^J - Cursor down ^K - Cursor up ^H - Cursor left ^L - Cursor right Input integers are decimal. Use 'h' suffix for hexadecimal entries. ----------------------------------------------------------------- Use the '=' key (which has the '+') or the RETURN key to advance the record. You don't have to use the shift key with the '=' key. EDFILE will wrap around to the start of the file when attempting to advance beyond the end of the file. The following paragraphs expand on the features available in EDFILE. Most of the options are self-explanatory from the help menus. However, some require additional explanations and are provided below. ADDRESS/OFFSET OPTIONS ---------------------- The address option allows you to specify an address within the file. This is useful for patching COM files and the like when the address of the patch is known. Note that when EDFILE'ing COM files, EDFILE automatically sets the offset to 0100h. The offset can be changed by typing 'O' at the command level and entering the desired offset. The headings will be adjusted for the different offset automatically. The address option always references the starting offset so that locations within programs which don't begin at 0100h (overlays, for example) can be easily referenced once the offset has been properly programmed. The Address option also has a wrap-around feature so that references below the current offset will be readjusted. This feature can be quite handy when tinkering around with COM files. You have to experiment a little to pickup the usefulness of these options. SEARCH OPTION ------------- The 'search' option is the most involved because it offers so many different possibilites. The description provided here should provide enough information to effectively use it. String searches normally start from the current record and proceed until the end of the file (EOF) is encountered. Certain suboptions can alter this sequence. If a match is not found, the program will indicate this and restore the screen to the record last displayed. The search can be aborted at any time by simply striking a key. If a string match occurs across records, the search will stop on the last record read into its' local buffer and position the cursor at the end of the found string. It just wasn't worth putting in the extra code to handle this wierd situation. When using the Occurrence ('O') and Mask ('M') suboptions, the program will prompt for the occurrence number and/or search mask to be used. The suboptions are inserted after a semicolon to delimit them from the search string entered. No spaces should be inserted between the suboptions. Upper or lower case is acceptable. Example: ?Search String = \This is great\;auo Stop on string occurrence = 3 This means to search for the string 'This is great' starting from the beginning of the file, ignoring the case of the string (i.e., translate lower to upper case) and stopping on the third occurrence of the string. ASCII strings must be delimitted by backslashes ('\'). The limitation here, of course, is that you can't search for backslashes in the file. So use the hex equivalent if necessary: 5C. The 'U' suboption (translate lower case to upper case) will translate the search string to upper case automatically, as well as converting all lower case characters read from the file. So, you don't have to input the search string in upper case when using the 'U' suboption. When inputting hexidecimal values as part of a search key, they MUST be two-digit HEX (not decimal) numbers. An invalid hex digit entry will cause an error and the string entry must be reentered. Two digits must be supplied for each hex number otherwise the search won't work properly. Upper or lower case for the hexidecimal letters is acceptable. Example: ?Search String = 40,FE,e5,05 You can mix hex entries with string entries within the search key. Example: ?Search String = 40,FE,\help me\,E5,05 The Backward search suboption (B) will start the search from the current record and continue towards the start of the file. It DOES NOT reverse the search string key, that is, if you enter \HELP\ for a search string key, it will not search backwards for \PLEH\. It only refers to the direction the records will be read while searching for a matching string. Also, each record is searched from the start of the record. The search stops when the start of the file (SOF) is encountered. The Mask suboption is for those cases where bytes in a file use certain bits for special meanings. The input mask is logically AND'd with each byte in the file before comparing it to the search string. Therefore, some bytes could pass the search test but still may not be exactly what your looking for. ?Search String = 03;M Enter string search mask = 0Fh This will mask all upper nibbles (upper 4 bits of each byte) and then compare it to a 3. Therefore, any data bytes which have a 3 in the lower nibble will cause a match with the search key. When the search string is found in the file, the search is temporarily terminated and the cursor is positioned at the start of the found string. Note, that the program is NOT in the edit mode, so the next key entered is a command not an edit control key. Hit a space (or any unrecognizable command) to redump the record and place the cursor on the command line. Hit an 'E' to go into the edit mode. The cursor will remain positioned at the start of the found string. CONTINUE SEARCH OPTION ---------------------- Hitting a 'C' at the command level will restart the search from the current record and cursor position (if previously defined). The search facility will then look for the NEXT occurrence of the entered string sequence. The 'O' suboption is affective only on the initial start of the search. The Continue ('C') option effectively disables the occurrence value previously entered. The default string occurrence is 1, i.e., the first (or next) occurrence. The Continue option can be invoked at any time after a search string key has been entered. All other suboptions are in affect when continuing the search. RECORD EDITING -------------- Record editing is accomplished by typing an 'E' at the command level. When in the edit mode, there are two modes of editing. You can edit the HEXIDECIMAL field area of the record or the ASCII field area. When entering the edit mode the cursor will be positioned at the upper left corner in the HEX data field of the current record. To switch to the ASCII data field of the record, simply enter a CTRL-E. This will toggle the cursor between the two fields. The HEX field area will only accept hexidecimal digits for inputs. The ASCII field will accept all key inputs including control key inputs if they are preceeded by an ESC key. For example: to input a CTRL-K into the record at the current cursor position, hit the ESC key followed by a CTRL-K. The ESC key simply means 'put the next input character into the record even if its' a control character'. This is only affective in the ASCII field area. Non-control characters (i.e., regular ASCII) can be typed in directly. To make the record changes permanently to the file, they must be flushed to the disk by typing a CTRL-W. Typing a CTRL-X will exit the edit mode without updating the file. BUGS: ==== There are currenly no know bugs. However, inputs are not completely validated, therefore, some conditions could cause different results. None, however, are know to cause file crashes or anything catastrophic. Any reports of bugs will be noted and appreciated. USE UNDER TURBODOS: ================== EDFILE is especially useful under TurboDOS. Using the filename $.DSK or $.DIR upon entering EDFILE allows editing of the disk and/or directory. I use EDFILE in every case when I need to look at the disk directory and make changes to it. The search facility makes this task a breeze. BACKGROUND INFO: =============== EDFILE was written in a language called SIL (Systems Implementation Language) which was obtained from DDJ and then enhanced and improved at Digilog, Inc for use in writing systems programs and utilities. SIL is very similar to 'C' but allows true inline 8080/Z80 assembly language coding (very useful) and compiles to actual assembly mnemonics. The output of the compiler is passed to Digital Research Inc's Relocatable Assembler (RMAC) and then to DRI's Linker (LINK). No special tricks were used in this program; that is, no system specific calls or locations were referenced, therefore, it should run on any CP/M or equivalent system. Of course, Murphy is lurking around, so don't depend on that assumption. FUTURE VERSIONS: =============== On the wish list is to add the capability to read and edit the data off of the disk on a track/sector basis. Any other ideas will be seriously considered in future versions of EDFILE. Thanks and good EDFILE'ing. Problems, suggestions or questions can be sent to me on my CompuServe number (#72345,1540) or via my home address: Mike Mosko 519 E. Station Ave. Coopersburg, PA 18036